{% extends "howto" %}

{% block main %}
<h2>Adding Tools</h2>
<p><em>Tools</em> have to be declared into the kit's <a href="howto/kit-config-file">metadata file</a>. Its name shall be a valid PHP name.</p>

<p>The Tool's class definition will have to be provided either by one of the kit's library files wihtin the [load_files] section, or by another kits listed as a dependancy.</p>

<p>You may add a cofniguration file for the Tool wich will be imported into the Tool's instance. You have to name it as the Tool's name followed by <q>.tool.ini</q>.</p>

<p>Let's add a <q>HttpRealmTool</q> tool, named <q>realm</q> to the kit <q>example</q>. The Tool's class is provided by the  kit <q>webappkit.httprealm</q>. We edit the <q>example</q> kit's metadata file (which is <q>example.wak/wak.ini</q>) as below :</p>
<code>[load_kits]
10 = "webappkit.httprealm"

[tools]
realm = "HttpRealmTool"</code>

<p>Then we create a config file (Which there set the users list) named <q>realm.tool.ini</q>. The config file format will be specific to each Tool class. We can then use the Tool, with a kit-specific configuration, with :</p>
<code>// getting the "example" kit
<var>$example</var>=&amp;Webappkit::getkit('example');

// using the "realm" tool
<var>$example</var>-><var>realm</var>->login();</code>

<h3>Building Tools</h3>
<p>Tools have to extend the <q>WakTool</q> class.
They must implement the Factory method for instanciation :</p>
<code>class ExampleTool extends WakTool {
    /**
    * a Factory function : every Tool has to implement it
    * this is because some PHP limitations
    * @static
    * @param string <var>$kit</var> kit's id
    * @param array <var>$cfg</var> configuration data taken from ini file
    * @return object tool's instance
    */
    static function Factory(<var>$kit</var>,<var>$cfg</var>) {
        return new ExampleTool(<var>$kit</var>,<var>$cfg</var>);
    }

    /**
    * @var array the default configuration values
    */
    protected <var>$cfg</var>=array(
        'section'=>array(
            'var'=>'value'));
}</code>

<p>Data from the configuration file will be dumped into <var>$cfg</var>.</p>
{% endblock %}
